//
// Copyright (c) 2002-2009 "Neo Technology,"
//     Network Engine for Objects in Lund AB [http://neotechnology.com]
// This file is part of Neo4j.
// 
// Neo4j is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as
// published by the Free Software Foundation, either version 3 of the
// License, or (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
// 
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
// 
#region Using Directives

using System.Collections.Generic;
using org.neo4j.graphdb;
using org.neo4j.kernel.impl.util;
using Node = org.neo4j.graphdb.Node;

#endregion
namespace org.neo4j.kernel.impl.traversal
{
    /// <summary> 
    /// A utility class that represents an arbitrary traversal over a nodespace. A
    /// Traverser is used as a tool for a Neo4j client programmer to easily traverse
    /// the node space according a complex set of rules.
    /// A Traverser is created by invoking any of the factory methods in
    /// <seealso cref="InternalTraverserFactory"/>. Subsequent retrieval of the nodes from a Traverser
    /// is simple: it can either be treated as an <seealso cref="IEnumerator "/> using
    /// the standard <CODE>if ( i.hasNext() ) { i.next(); }</CODE> idiom or as a
    /// Traverser with the type-safe <seealso cref="NextNode"/> or the array-based
    /// <seealso cref="GetAllNodes"/> operations.
    /// A Traverser is generally not thread safe. If a client wishes to use it in a
    /// concurrent environment, they are strongly adviced to synchronize externally. 
    /// </summary>
	public interface InternalTraverser : Traverser
    {
        #region Implementations

        /// <summary> 
        /// Returns the next node in the traversal. 
        /// </summary>
        /// <exception cref="NoSuchElementException">
        ///            if the traversal has no more nodes </exception>
        ///<returns> the next node in the traversal </returns>
        ///  <seealso cref= "NextNode"> </seealso>    
		object Next();
        ///<summary>
        ///  Returns <CODE>true</CODE> if the traversal has more nodes. In other
        ///words, returns <CODE>true</CODE> if <seealso cref="#next"/> or <seealso cref="#nextNode"/>
        ///would return a node rather than throwing an exception. 
        /// </summary>
        ///<returns> <CODE>true</CODE> if the traversal has more nodes </returns>
		bool HasNext(); 
        ///<summary> 
        /// Unsupported, throws an <seealso cref="UnsupportedOperationException"/>. 
        /// </summary>
        ///<exception cref="UnsupportedOperationException">
        ///            always when this operation is invoked </exception>
		void Remove();  
        ///<summary> 
        /// Returns the next node in the traversal. This operation is identical to
        ///<seealso cref="Next()"/> except that it's type safe. 
        /// </summary>
        ///<returns> the next node in the traversal </returns>
        ///<exception cref="NoSuchElementException">
        ///            if the traversal has no more nodes </exception>
		Node NextNode();
        ///<summary> 
        /// Returns all remaining nodes in the traversal as an array, <B>PLEASE NOTE</B>
        ///that this operation can potentially be VERY CPU consuming and leave
        ///little room for performance-boosters such as background streaming of
        ///content from persistence and cache spooling. Only use this method if you
        ///know that the traverser is well-behaving and won't run wild and try to
        ///return the entire node space. 
        /// </summary>
        ///<returns> an array of all the nodes in this traversal </returns>
        new List<Node> GetAllNodes();
        ///<summary> 
        /// Returns a Traverser for all remaining nodes sorted as specified by 
        ///<CODE>NodeSortInfo</CODE>.
        ///<B>PLEASE NOTE</B> that this operation can potentially be VERY CPU
        ///consuming and leave little room for performance-boosters such as
        ///background streaming of content from persistence and cache spooling. Only
        ///use this method if you know that the traverser is well-behaving and won't
        ///run wild and try to return the entire node space.
        /// </summary>
        ///<param name="nsi">
        ///           encapsulates how the nodes should be sorted </param>
        ///<returns> a sorted traverser for all remaining nodes </returns>
		InternalTraverser Sort(NodeSortInfo<Node> nsi);

        #endregion
    }
}